home *** CD-ROM | disk | FTP | other *** search
/ BCI NET 2 / BCI NET 2.iso / archives / demos / misc / gettintired.dms / in.adf / Libs / PTReplay.doc < prev    next >
Encoding:
Text File  |  1995-01-03  |  12.1 KB  |  488 lines
  1. -----------------------------------------------------------------------
  2.  
  3. PTReplay.library version 4.16 by Mattias Karlsson. © 1994 BetaSoft
  4. This version is FreeWare. You may use this library, and also copy it 
  5. further, provided that NO CHARGE is claimed. This message must always
  6. accompany any files in the PTReplay.library that is distributed.
  7.  
  8. -----------------------------------------------------------------------
  9.  
  10. This is ptreplay.library version 4. It is a standard Amiga shared library,
  11. capable of replaying ProTracker modules.
  12. The replay routines are 99% system-friendly¹, and use CIA timing, which
  13. gives a smoother replaying.
  14.  
  15. Use this library as you would use any normal Amiga library. Included in
  16. this package is include files for Assembler and C. 
  17.  
  18. I wrote this library because I was unable to find a _good_ and system-
  19. friendly replay routine for ProTracker. I based this loosely on the 
  20. example sources that accompany ProTracker, but these were pretty badly
  21. written, and sparsly commented, and the CIA routines did never work on
  22. my machine. A job worth doing well is worth doing yourself, I though
  23. and went to work. This is what emerged, a small library. Notice that it
  24. is not much larger than 6k, and still contains all needed to play good 
  25. music.
  26.  
  27. NOTE: All library functions are safe to call with a NULL parameter.
  28.  
  29. If you want to contact me for any reason, you can write to:
  30.  
  31.   UUCP:  Mattias_Karlsson@augs.se  or  BetaSoft@augs.se
  32.   FIDO:  Mattias Karlsson@2:205/425.0
  33.  
  34. SNAIL: BetaSoft
  35.        Mattias Karlsson
  36.        Slöjdgatan 6
  37.        S-930 61  Bastuträsk
  38.        SWEDEN
  39.  
  40. Changes from 3.20 to 4.15
  41. -------------------------
  42.  
  43. * New funktions to read SongPosition, SongPattern, PatternPos and PatternData
  44.  
  45. * New funktion that lets you be signaled on Song Restart, new pattern and
  46.   new patternrow.
  47.  
  48. * The ability to play an already loaded module.
  49.  
  50. * New faderoutine that doesn't wait until the fading is done and then
  51.   automaticly stops the song.
  52.  
  53. Changes from 3.12 to 3.20
  54. -------------------------
  55.  
  56. * Removed that sometimes made a tempochange to cause a systemhang.
  57.  
  58. * Removed the fact that changing the tempovalue also resets the speed to 6.
  59.   The speedvalue is now left unchanged.
  60.  
  61. Changes from 2.0 to 3.12 (3.0 was only a betarelease)
  62. -----------------------------------------------------
  63.  
  64. * Added the abillity to change volume on a module while it is playing.
  65.  
  66. * Removed a bug in command 6 (VibratoPlusVolSlide) that made a downslide
  67.   always reset volume to 0.
  68.  
  69. * Changed the way on how the volume is changed in fade and setvolume commands
  70.   to make in sound more natural.
  71.  
  72. These are features I would like to add:
  73. --------------------------------------
  74. * Various small enhancements and speed increases.
  75.  
  76. * spliting a module intro several blocks (Currently it loads into one block).
  77.  
  78. * Temporary storing of modules in fastmem.
  79.  
  80. ---------------------------------------------------------------------------------
  81. ¹ 99% because the library doesn't reserve the sound channels it uses. If
  82.   you want this feature in your program, you'll have to do it yourself,
  83.   using audio.device².
  84.  
  85. ² See 'Rom Kernel Reference Manual: Devices' for information on how to use
  86.   audio.device and reserve sound channels.
  87.  
  88. *********************************************************************************
  89.  
  90. NAME
  91.     PTLoadModule
  92.  
  93. SYNOPSIS
  94.     module = PTLoadModule(name)
  95.        D0                 A0
  96.  
  97.     struct module *PTLoadModule(STRPTR);
  98.  
  99. FUNCTION
  100.     Attempts to load the module named.
  101.  
  102. INPUTS
  103.     name - pointer to null-terminated string containing name of module.
  104.  
  105. RESULT
  106.     module - pointer to module control structure or NULL if failed.
  107.  
  108. SEE ALSO
  109.     PTSetupMod
  110.  
  111. -----------------------------------------------------------------------------
  112.  
  113. NAME
  114.     PTUnloadModule
  115.  
  116. SYNOPSIS
  117.     PTUnloadModule(module)
  118.                    A0
  119.  
  120.     void PTUnloadModule(struct Module *);
  121.  
  122. FUNCTION
  123.     Frees all memory used by the module.
  124.  
  125. INPUTS
  126.     module - pointer to module control structure.
  127.  
  128. BUGS
  129.     Does not check that module is stopped. If you call this function on
  130.     a module that is playing, you _will_ cause a System Failure. You
  131.     have been warned.
  132.  
  133. -----------------------------------------------------------------------------
  134.  
  135. NAME
  136.     PTPlay
  137.  
  138. SYNOPSIS
  139.     PTPlay(module)
  140.            A0
  141.  
  142.     void PTPlay(struct Module *);
  143.  
  144. FUNCTION
  145.     Start playing the module from the beginning. If this module already
  146.     was playing, it starts over from the beginning.
  147.  
  148. INPUTS
  149.     module - pointer to module control structure.
  150.  
  151. BUGS
  152.     It is not yet supported to call this function while another module
  153.     is playing.
  154.  
  155. -----------------------------------------------------------------------------
  156.  
  157. NAME
  158.     PTStop
  159.      
  160. SYNOPSIS
  161.     PTStop(module)
  162.            A0
  163.  
  164.     void PTStop(struct Module *);
  165.  
  166. FUNCTION
  167.     Stop playing the indicated module. If it wasn't playing, nothing
  168.     happens.
  169.      
  170. INPUTS
  171.     module - pointer to module control structure.
  172.  
  173. -----------------------------------------------------------------------------
  174.  
  175. NAME
  176.     PTPause
  177.      
  178. SYNOPSIS
  179.     PTPause(module)
  180.             A0
  181.  
  182.     void PTPause(struct Module *);
  183.  
  184. FUNCTION
  185.     Pause this module, remembering the position so that you can restart
  186.     it later. All sound is turned off.
  187.      
  188. INPUTS
  189.     module - pointer to module control structure.
  190.  
  191. SEE ALSO
  192.     PTResume
  193.  
  194. -----------------------------------------------------------------------------
  195.  
  196. NAME
  197.     PTResume
  198.      
  199. SYNOPSIS
  200.     PTResume(module)
  201.              A0
  202.  
  203.     void PTResume(struct Module *);
  204.  
  205. FUNCTION
  206.     Resume playing this module, after it was paused. If it was not paused
  207.     then nothing happens.
  208.  
  209. INPUTS
  210.     module - pointer to module control structure.
  211.  
  212. SEE ALSO
  213.     PTPause
  214.  
  215. -----------------------------------------------------------------------------
  216.  
  217. NAME
  218.     PTFade (V2)
  219.  
  220. SYNOPSIS
  221.     PTFade(module,speed)
  222.            A0     D0
  223.  
  224.     void PTFade(struct Module *, UBYTE);
  225.  
  226. FUNCTION
  227.     This function does smooth vol slidedown until volume reaches zero, then
  228.     the module is stoped and the function returns. The speed is given
  229.     in the number of "vblanks" (ie CIA timeouts because it uses CIA timing
  230.     instead of vblank timing) between each step.
  231.  
  232. INPUTS
  233.     module - module that is to be stoped.
  234.     speed - fading speed.
  235.  
  236. SEE ALSO
  237.     PTStartFade
  238.  
  239. -----------------------------------------------------------------------------
  240.  
  241. NAME
  242.     PTSetVolume (V3)
  243.  
  244. SYNOPSIS
  245.     PTSetVolume(module,volume)
  246.                 A0     D0
  247.  
  248.     void PTSetVolume(struct Module, UBYTE);
  249.  
  250. FUNCTION
  251.     Change the volume of a module while it is playing.
  252.  
  253. INPUTS
  254.     module - pointer to module.
  255.     speed  - new volume  0-64 ($00-$40)
  256.  
  257. -----------------------------------------------------------------------------
  258.  
  259. NAME
  260.     PTSongPos (V4)
  261.  
  262. SYNOPSIS
  263.     Pos=PTSongPos(module);
  264.     d0            A0
  265.  
  266.     UBYTE PTSongPos(struct Module *)
  267.  
  268. FUNCTION
  269.     This function returns the position the module is curently playing.
  270.  
  271. INPUTS
  272.     module - pointer to a module that is playing.
  273.  
  274. RESULTS
  275.     Pos - What position that is playing (0 - (Length-1) ) or 0 if not playing
  276.  
  277. -----------------------------------------------------------------------------
  278.  
  279. NAME
  280.     PTSongLen (V4)
  281.  
  282. SYNOPSIS
  283.     Len=PTSongLen(module)
  284.     d0            a0
  285.  
  286.     UBYTE PTSongLen(struct Module *);
  287.  
  288. FUNCTION
  289.     This funktion returns the length of the module is positions. This is the
  290.     same value as Length in ProTracker and means that it will play until
  291.     position Len-1.
  292.  
  293. INPUTS
  294.     module - The module whos length you which to now.
  295.  
  296. RESULTS
  297.     Len - Number of positions in module
  298.  
  299. -----------------------------------------------------------------------------
  300.  
  301. NAME
  302.     PTSongPattern (V4)
  303.  
  304. SYNOPSIS
  305.     PatNum=PTSongPattern(module, pos)
  306.     D0                   A0      D0
  307.  
  308.     UBYTE PTSongPattern(struct Module *,UWORD);
  309.  
  310. FUNCTION
  311.     Returns the pattern number at a given position.
  312.  
  313. INPUTS
  314.     Module - The module you want to examine
  315.     Pos - The position (0-127) you want to examine.
  316.  
  317. RESULTS
  318.     PatNum - A number (0-127) telling you which pattern is to be played.
  319.  
  320. -----------------------------------------------------------------------------
  321.  
  322. NAME
  323.     PTPatternPos (V4)
  324.  
  325. SYNOPSIS
  326.     Row=PTPatternPos(module)
  327.     D0               A0
  328.  
  329.     UBYTE PTPatternPos(struct Module *);
  330.  
  331. FUNCTION
  332.     Returns the row in the pattern that it is currently being played.
  333.  
  334. INPUTS
  335.     module - A module that is currently being played.
  336.  
  337. RESULTS
  338.     Row - The row (0-63 $00-$40) that is being played.
  339.  
  340. -----------------------------------------------------------------------------
  341.  
  342. NAME
  343.     PTPatternData (V4)
  344.  
  345. SYNOPSIS
  346.     RowData=PTPatternData(Module, PatternNum, RowNum)
  347.     D0                    A0      D0          D1
  348.  
  349.     APTR PTPatternData(struct Module *, UBYTE, UBYTE);
  350.  
  351. FUNCTION
  352.     This function returns a pointer to the given row in the a specified
  353.     pattern.
  354.  
  355. INPUTS
  356.     Module - Pointer to the module you which to examine.
  357.     PatternNum - The pattern (0-127) you want to examine.
  358.     RowNum - And finaly the which row (0-63) to examine.
  359.  
  360. RESULTS
  361.     RowData - An adresspointer to the given position
  362.  
  363. -----------------------------------------------------------------------------
  364.  
  365. NAME
  366.     PTInstallBits (V4)
  367.  
  368. SYNOPSIS
  369.     PTInstallBits(Module, Restart, Pos, Row, Fade);
  370.                   A0      D0       D1   D2   D3
  371.  
  372.     void PTInstallBits(struct Module *, BYTE, BYTE, BYTE, BYTE);
  373.  
  374. FUNCTION
  375.     This function is used to inform ptreplay which signals to send to this
  376.     task at the given positions. Currently it can only be set up to signal
  377.     one task/module (the one calling this function) this may however change
  378.     in future. A signalbit of -1 tells ptreplay not to signal you at that
  379.     specific location.
  380.  
  381. EXAMPLE
  382.     /* This will set signalbit 4 when the module restarts from the beginning */
  383.     PTInstallBits(Module, 4, -1, -1, -1);
  384.  
  385.     /* This will set signal 0 when startfade has stopped the module */
  386.     PTInstallBits(Module, -1, 1, -1, 0);
  387.  
  388. INPUTS
  389.     Module - module to use the given signals
  390.     Restart - Bit to set when a module restarts from beginning or -1 for no
  391.         signal
  392.     Pos - Bit to set when moving to next position or -1 for no signal
  393.     Row - Bit to set when moving to next row in pattern or -1 for no signal
  394.     Fade - Bit to set when PTStartFade is done and have stoped module or -1
  395.         for no signal.
  396.  
  397. SEE ALSO
  398.     PTStartFade
  399.  
  400. -----------------------------------------------------------------------------
  401.  
  402. NAME
  403.     PTSetupMod (V4)
  404.  
  405.     Module = PTSetupMod(LoadedMod);
  406.     D0                  A0
  407.  
  408.     struct Module *PTSetupMod(APTR);
  409.  
  410. FUNCTION
  411.     This function will allocate a module control structure and intilize it
  412.     using an already loaded module file, in order to use in with ptreplay.
  413.  
  414. EXAMPLE
  415.     /* This routine will do the same thing as PTLoadMod */
  416.     BPTR File;
  417.     APTR Mod;
  418.     int Len;
  419.     struct Module *Module;
  420.  
  421.     File=Open("mod.module",MODE_OLDFILE))
  422.     Seek(File, 0l, OFFSET_END);
  423.     Len=Seek(File, 0l, OFFSET_BEGINNING);
  424.  
  425.     Mod=AllocMem(Len, MEMF_CHIP);
  426.     Read(File, Mod, Len);
  427.     Close(File);
  428.     Module=PTSetupMod(Mod);
  429.  
  430. NOTE
  431.     1. The module MUST already be located in chip mem.
  432.     2. The module MUST be valid while the module is goint to be used.
  433.     Both may change in future.
  434.  
  435. INPUTS
  436.     LoadedMod - An pointer to an already loaded module.
  437.  
  438. RESULTS
  439.     Module - A module structure to be used 
  440.  
  441. SEE ALSO
  442.     PTFreeMod
  443.  
  444. -----------------------------------------------------------------------------
  445.  
  446. NAME
  447.     PTFreeMod (V4)
  448.  
  449. SYNOPSIS
  450.     PTFreeMod(Module)
  451.               A0
  452.  
  453.     void PTFreeMod(struct Module *);
  454.  
  455. FUNCTION
  456.     This function will free all memory allocated by the PTSetupMod function.
  457.  
  458. INPUTS
  459.     Module - a module returned by PTSetupMod().
  460.  
  461. SEE ALSO
  462.     PTSetupMod
  463.  
  464. -----------------------------------------------------------------------------
  465.  
  466. NAME
  467.     PTStartFade (V4)
  468.  
  469. SYNOPSIS
  470.     PTStartFade(Module, Speed)
  471.                 A0      D0
  472.  
  473.     void PTStartFade(struct Module *, UBYTE);
  474.  
  475. FUNCTION
  476.     This function will also do a smooth volume slidedown in the same way
  477.     as PTFade does but it returns as soon as the fading has started instead
  478.     of when it is done. Currently the only way to notice when the module
  479.     is stoped is to setup a Fade bit using PTInstallBits and check for that
  480.     bit.
  481.  
  482. INPUTS
  483.     Module - Module to be stoped.
  484.     Speed - fading speed.
  485.  
  486. SEE ALSO
  487.     PTFade, PTInstallBits
  488.